This document describes the specific functions of the Macintosh version of POV-Ray. It is assumed that you have read (or will read) the POVRAY.DOC file that describes the general operation of POV-Ray. There is also a “POV-Ray 2.x ReadMe” file, which explains the requirements, functionality, and has a brief installation and quick-start section.
Here's a list of topics in this document:
The POV-Ray Preferences dialog, up close
The Rendering Options dialog, up close
The Animation Settings dialog, up close
Advanced Tips
To speed up rendering as much as possible…
To edit large scene files…
To batch-render a series of individual scene files…
To generate a QuickTime movie from POV-Ray…
Bugs, Quirks, and Future Directions
The Bad News...
The Good News, Coming sometime after version 2.0...
The Source Code
Think C Compiler Notes
MPW C Compiler Notes
The POV-Ray Preferences dialog, up close
-------------------------------------
This dialog sets up general preferences for the POV-Ray application that will be remembered between renders, and between separate runs of POV-Ray itself. Here is a description of what each item does:
(1) Application Friendliness - The higher the number, the more time POV-Ray takes from other applications, and the faster it runs (and the slower and more jumpy the other applications become.)
(2a) Use Application's Default Rendering Options - To use the Application Default Rendering Options for rendering files (ignoring each file's unique Rendering Options), click here. This is normally used for multiple rendering sessions.
(2b) Use each file's Rendering Options - To use each file's unique Rendering Options, click here. This is normally used for single rendering sessions.
(3a) Notify When Complete - Select one of these items to tell POV-Ray what to do when it finishes rendering the scene or scenes. It can finish quietly or it can notify you. 4b below lets you set HOW it notifies you.
(3b) Notification Style - Select one of these items to tell POV-Ray how to notify you when it finishes rendering the scene or scenes. It can either beep, display a dialog, or do both.
(4) Set Include Folder - Click this button to choose which folder POV-Ray should look in for files specified in the "#include" statements. It will also look in the same folder as the original scene being rendered. Just below this button is the path to the current folder it will look in.
The Rendering Options dialog, up close
----------------------------------
This dialog sets up specific rendering options for the current scene file. These options are stored with the scene file itself (in the respurce fork) and are remembered on subsequent renders of the scene file. Here is a description of what each item does:
(1a) Preset Image Sizes - Selecting an image size here will automatically fill in the width/height/from/to fields below with a preset size. Many screen sizes are listed here.
(1b) Width - Enter the total width of the image you want to render (in pixels.) This number can be from 1 to 4096.
(1c) Height - Enter the total height of the image you want to render (in pixels.) This number can be from 1 to 4096.
(1d) From row - Enter the top scanline, or starting row, of the image you want to render (in pixels.) Only enter a number here if you want to render a partial image.
(1e) To row - Enter the bottom scanline, or ending row, of the image you want to render (in pixels.) Only enter a number here if you want to render a partial image.
(2) Progress - Sets how much information is displayed in the status window as the render progresses. "No Info" is quiet, "Minimal Info" shows some memory usage information, "Progress Info" informs you of each scanline, "Debug Info" shows internal debug information. See POVRAY.DOC for more information on the "+V" option.
(3) Image Quality - Enter a number (from zero to nine) to select the quality of the rendered image. 1 just shows grey shapes, 5 shows colors, 9 shows full shadows lights and refraction. The lower the number, the lower the quality and the faster the render.See POVRAY.DOC for more information on the "+Q" option.
(4) Auto-bounding - Turn this popup on to let POV-Ray optimize your scene by automatically "bounding" the objects in your scene. The number you set is the minimum number of main objects it finds before it decides to kick in auto-bounding. See POVRAY.DOC for more information on the "+MB" option.
(5a) Animate - Turn this on if you want to create a sequence of multiple images from this scene file. See POVRAY.DOC for more information on the "+K" option.
(5b) Animate Settings - Click this to set up the number of frames, clock value range, etc. for animation.
(6) Language - Set this to which version of POV-Ray syntax this file is written in (version 1.0 or 2.0.) See POVRAY.DOC for more information on the "+MV" option.
(7a) Compress Image - Turn this on to automatically use QuickTime image compression on the output PICT file when it is saved.
(7b) Compression Settings - Click this to set up what kind of image compression to use on the PICT file.
(8) Max Symbols - Set this to the largest number of #declared items in your scene file. See POVRAY.DOC for more information on the "+MS" option.
(9a) Do Anti-aliasing - Click here to toggle “anti-aliasing” of the image. Although the rendering can take much longer when this is on, the final image is much nicer looking, with fewer jagged edges. See POVRAY.DOC for more information on the "+A" option.
(9b) Threshold - Enter a number here (from 0.0 to 1.0) that determines the threshold depth of anti-aliasing. The closer to 0.0, the more anti-aliasing is done, the better the image looks, and the longer it takes to render.
(9c) Depth - Enter a number from 1 to 9 here to set the recursive depth of anti-aliasing. The number of rays is the square of this number, so a 3 would create 3*3 or 9 rays, etc.
(9d) Jitter - Enter a number from 0.0 (no jitter) through 1.0 (lots of jitter.) The higher this number, the "wider" the anti-aliasing area, and the smoother it looks.
(10a) Create Targa Output File - To toggle the creation of a Targa-format output file during the render process, click here. This can allow you to stop POV-Ray partway through, and run it later to finish from where it left off.
(10b) Continue Rendering with Targa - To tell POV-Ray to load the Targa file from the previous run and to continue where it left off last, click here.
(11) Save as defaults for new files - To save the current Rendering Option Settings as the Application's Default Settings, click here. All new documents will then acquire these default Rendering Options.
The Animation Settings dialog, up close
----------------------------------
This dialog sets up how many frames of animation to generate, and how the clock variable should change across the frames. Note the outer bounds (Initial and Final) are used for calculating the overall number of frames and values for the scene. The inner bounds (Start at and End at) are used to determine which frames to actually generate for this session. Here is a description of what each item does:
*** Frame Number. This is just a reference number which counts the number of frames (or images) to generate. It starts at one, and increments for each frame.
(1a) Initial - This is a constant low bound for the frame counter. It is always one.
(1b) Start At - This is the first frame number to start generating images for. It can be any integer number from "Initial" to "End at".
(1c) End At - This is the last frame number to generate images for. It can be any integer number from "End at" to "Final".
(1d) Final - This is the high bound for the frame counter. It is the total number of frames that should be generated for the scene. This is used to calculate the span of clock values.
*** Clock Value. This is a variable passed into POV-Ray, which can be used as a dynamically changing animation variable (clock) in a scene file.
(1a) Initial - This is the clock value at frame #1. It must be different than the "Final" clock value, but otherwise may be any floating point value.
(1b) Start At - This is the displayed clock value at the "Start At" frame value.
(1c) End At - This is the displayed clock value at the "End At" frame value.
(1d) Final - This is the clock value at the "Final" frame #. It must be different than the "Initial" clock value, but otherwise may be any floating point value.
Advanced Tips
-------------
***
*** To speed up rendering as much as possible on the Mac…
***
If you are in the beginning stages of scene creation, you often find yourself editing, rendering, editing, rendering, etc. To speed this up, try shrinking the image size to 32x32, and using the quick_color statements and setting the Image Quality down to about 3. Also hiding the image window during rendering speeds up POV-Ray a bit. If you are generating a final scene, try temporarily booting your Mac with no (or few) extensions on. Some of these, especially screen savers and network connections, can really slow things down. POV-Ray grabs more time if it is in the foreground, so don't switch it out behind others. Also, choose the POV-Ray Preferences item from the Edit menu, and set the Application Friendliness throttle way up, towards 11. Doing all of this can dramatically speed up the scene generation.
***
*** To edit large scene files…
***
Because of the current file size limitation in the POV-Ray built-in editor, you must make sure that the main “.POV” file is no larger than 32K bytes. To edit and render larger files, you must use another text editor to break the file into a small .POV file, which uses the #include statement to use the larger file(s). You can then edit and render the .POV file with POV-Ray. The larger include files must still be edited with another text editor. Note that if you use a word processor to do this (e.g. MacWrite, Word, WriteNow, etc.), you must save the file in “Text-Only” format.
***
*** To batch-render a series of individual scene files…
***
If you are rendering a few files of different output sizes/parameters, open each file in POV-Ray and set up its “Rendering Options” the way you want, and close each file when done. There should be no POV-Ray Source file window open now. Don't quit POV-Ray, but instead just switch to the System 7 Finder. Select all the files which you just opened and set options for. Now drag them over onto the POV-Ray application icon (or convenient application alias) and drop them on it. POV-Ray will (by default) render each file with its own option settings, and save each image before starting the next.
If during this batch rendering process, you want to add more files to the list, just drag the new files onto POV-Ray just like before. These new files will be added to the end of the list of files to batch-render.
To stop the batch rendering in progress, just choose "Stop Rendering" from the Render menu, or press command-period. The current scene will be interrupted, and all remaining scenes will not render. To resume, you will have to drop the remaining scene files onto POV-Ray again.
If you want a series of images to all be rendered, but with identical settings, then do this: Open any one of the files to be rendered, and set up its Rendering Options the way you want all the files to be done. Now choose “Application Preferences” from the File menu. Turn on the “Use Application Default Options” radio button, and turn on the “Save current file's rendering options as the default” checkbox, and click the Save button. Close the source window, but DON'T QUIT POV-RAY YET! Now switch back to the Finder, select all the files, and drag them onto the POV-Ray application icon, just like before. This time, all the files will ignore their individual settings, and use the default application setting.
NOTE: In the interest of safety and user sanity, POV-Ray doesn't remember this override state, but always returns to “…each file's settings…” when it is first run.
***
*** To generate a QuickTime movie from POV-Ray…
***
Use the “clock” variable in expressions in your scene, to scale, translate, or rotate objects. Then use the “Rendering Options” menu item, turn on the “Animate” checkbox, and click the “Settings” button to set the number of frames and the range of the clock variable. When you render the file, it will render multiple times and generate a series of PICT files. You can then use MacroMind Director, Apple's Convert-to-Movie, my FreeWare "MooVer" utility, or some other application to “import” the series of PICT files, and save the result as a QuickTime movie.
To stop the animation rendering in progress, just choose "Stop Rendering" from the Render menu, or press command-period. The current scene frame will be interrupted, and all upcoming frames will not render.
To resume from some frame, you can choose "Animation Settings" from the Rendering Options dialog, and set the "Start At:" to start where you left off. POV-Ray will then begin rendering from that frame to the "End At:" frame.
An example of a spinning box and a moving sphere is shown below:
box { <-1,-1,-1> <1,1,1> rotate clock*y }
sphere { <0,0,0> 2 translate clock*z/36-5 }
If you set up the frames to go from 1 to 20, and the clock value to go from 0 to 360, then the above box will make one complete revolution, and the sphere would move from -5 z to +5 z. The math is left as an exercise to the reader :-)
Animation tip: If you are creating an animation that you want to smoothly loop, there is a subtle problem you might run into. If you set up the animation to go from 0.0 to 360.0 degrees, you will notice that the first and last frames are the same, since in the
"polar regions", zero is the same as 360. This means that at the loop point of the movie, there will be a slight stall because the same frame is displayed twice. To get around this problem, you must do the following:
Set the Final frame to be one more than you actually want (e.g., 101), and set the "End At:" frame at one less than this (e.g., 100). Now set the "Start At:" frame number to 1, and set the Initial and Final clock values to the full range (e.g., 0.0 to 360.0)... whew, now you are ready to make a movie! Of course, you could just delete one of the frames and have a 99 frame movie, but that would be too easy.
Bugs, Quirks, and Future Directions
-----------------------------------
The Bad News...
************
* There is a maximum limit of 32,000 characters (approx. 32K bytes) in source files in the built-in text editor window. The text editor will not allow you to open or create files bigger than this. This is due to a limitation of the Macintosh TextEdit package (i.e., Programmer Laziness.) Although the main file to be rendered must be less than 32K in size, any #included (.INC) files may be of any size. You will just need to use some other editor or word processor to edit those. If you do use a word processor to edit them, remember to save your files in TEXT-only format.
* There is this same 32K limit in the Status window text. When the Status Window gets close to this limit, it just drops things off the top as it adds to the bottom. So you always have the last 32K of text in the window.
* If you create and render a scene file with nothing in it, it will display an error "no objects found in scene." If you try to run the same scene again, you will get some odd error messages.
* After each rendering job, POV-Ray "loses" about 1 KByte of RAM memory. This sloppy phenomenon, sometimes known in programming circles as a "memory leak", is not harmful. However, after you've done a large number of renders without quitting the application, you may eventually get an "out of memory" error. Just quit and restart POV-Ray, and it will be fine for awhile again. This will be more of a problem if you are doing animation renders with lots of frames. You may have to break it into multiple runs, or increase POV-Ray's application heap size. This was addressed prior to release, but not all leaks were found... it will be completely fixed in a future release. All "direct" memory leaks are fixed, what's left seems to be caused by calling runtime routines that themselves leak.
* POV-Ray should be creating the POV-Ray Virtual Image Buffer file in the Temporary Items folder if it is running under System 7, it currently does not.
* There is still an occasional quirk in the vertical scrollbar of the Status window, where it will get out of sync if you scroll it while the window is being filled. Nothing is lost, and if you scroll to the top and back to the bottom, all returns to normal.
* There are reports that the "Finder Balloon Help" of the POV-Ray Application (turn on Balloon Help and point at app in the Finder) does not work on some Macs. It will report a Finder "Type -192" error. It seems to work properly on other machines. This may be due to a corrupt desktop database, although rebuilding the desktop was reported not to help.
* Under System 6.x, POV-Ray will not automatically open a document that is double clicked from the Finder. You must run POV-Ray, then open the file from the File menu. Double-clicking documents DOES work properly in System 7, and in fact, multiple file drag-n-drop is supported. This missing System 6 feature was an intentional omission due to time constraints and the low priority of the feature.
* If you are using a virtual image buffer for a large image, it is not advisable to use the "Size Image to Window" mode, because the image won't display properly. This is only a display problem, It will save properly when finished.
* Adobe Photoshop prior to version 2.5 ignores the vertical-flipped bit of the TARGA files created by POV-Ray, and displays them upside down. Version 2.5 fixes this problem.
* With System 7 Virtual Memory (VM) on, and anti-alias setting on, and an anti-alias on, the VM file will do some thrashing occasionally if your rendering requires a virtual image buffer. This will just slow things way down; it doesn't cause any crashes.
The Good News, Coming sometime after version 2.0...
*****************************************
* Allow selecting an arbitrary area in Image window, and then re-rendering just that area (x1,y1 to x2,y2).. more flexible than the current start/end scanline method
* Allow user to scroll the Image window
* Let user pick file signature for PICT and Targa file formats. Currently, PICT files are saved with TeachText's signature and Targa files are saved with PhotoShop's (PICT creator type is currently saved in scene file's fPrf resource, & could be edited with ResEdit.)
* Built-in QuickTime movie support
* TIFF and PICT image (image-map) support for POV-Ray
* TrueType font support (extruded characters.. need generic POV-Ray syntax additions for typeface import?)
* Allow saving image directly to GIF or 8 bit Mac PICT format (currently just 24 bit PICT now.)
* Mac Network (distributed) rendering
The Mac Source Editor needs a _major_ facelift, to include:
* Abandon stock TextEdit, support source files larger than 32K chars
* Support tabs
* Search and replace features should be added
* Shape prototype generation, esp. torus and other tough ones
* Add balanced curly brace checking
* Simultaneously edit multiple source files, useful for Includes
One possible way to enhance the editor is to give up on the built-in text editor altogether, and tell the user to use BBEdit or some other text editor, and we could break POV-Ray into a faceless rendering engine that accepts AppleEvents. The options dialogs could be supported by a stand-alone application that could alter the file's settings prior to rendering. This makes POV-Ray more loosely coupled, but paves the way for drop-in editors and network rendering. Besides the time it would take to do this, an interesting obstacle to overcome is how the rendering engine would display its image. If it was not so tightly integrated, quick changes and re-rendering sessions may be more awkward. These are some interesting ideas... we are interested in hearing from users as to which way future versions of POV-Ray should head, let us know!
The Source Code
---------------
POV-Ray is a team effort, and the team members use Compuserve's Graphics Developers forum (GRAPHDEV) to keep abreast of changes and suggestions. Before you dive in and write massive enhancements, we suggest that you contact any of the team members and get to know the guidelines. We are an easy going bunch, and very friendly and interested in helping newcomers. And who knows, we may be working on the very same features you want to add, or your enhancement may be one we're hoping to see done. If you wish to make changes to POV-Ray, read the Port Guide, found in the POVSRC archive under MISC:PORTGUID.DOC.
Before you publically post altered source or executables, please review the POV-Ray legal documentation for copyright restrictions and rules of distribution. POVLEGAL.DOC can be found in any of the archives. To restate our position: please contact us directly with any bug fixes or enhancements. We can then incorporate them into the next general release.
The executables released by the POV Team for the Macintosh are built using Think C 6.0. It is possible to create even faster POV-Ray executables using a mix of Gnu C and MPW, but for a straight compilation, Think C 6.0 is a little smaller and faster than MPW 3.2 or MPW 3.3.
You will find the source code in two sections in the POVSRC archive. The main portion of POV-Ray is in POVSRC:SOURCE:. The additional Macintosh-specific source code is in POVSRC:MACHINE:MAC-Source:. These two sets of source should then be put together into a single POV-Ray Source folder before building (any name is fine.)
Some Apple header files for QuickTime compression are also included. These are mainly for the Think C 5 & 6 environment, as they are already present in MPW 3.3. If you're trying to build a version and add newer QuickTime features (1.61 is current as of this release), you may need to get newer header files from Apple or Symantec, or whoever is doing Apple's development system these days :-)
Think C Compiler Notes
------------------------
When compiling, you must use Think C 5.0 or later (preferably 5.0.4 or 6.0.) The enclosed Project file "POV.π" is for Think C 6.0. To compile under Think C 5.x, you will need to throw this file away and create a new one from scratch. Notes on how to do this are listed below.
Think C 5 & 6 don't have the following QuickTime headers, so we have provided them for now. You will need to copy them into Think C's "Apple Includes" folder.
ImageCodec.h
ImageCompression.h
MediaHandlers.h
Movies.h
MoviesFormat.h
QuickTimeComponents.h
You should first make a COPY of your "Standard Libraries:ANSI" library's Project file, and rename your copy to “ANSI-020.FPU.NoConsole”. This will be the ANSI library you'll be using for POV-Ray. Remove the files "console.c" and "command.c" from the project. Choose the Edit:Options menu, and change the following: Think C:Compiler settings, turn on all checkboxes except "4 byte ints" and "8 byte Doubles". Code Optimizations:turn on all, but not the Global Optimizations. Debugging:turn off all. Prefix:add a #define _NOCONSOLE_. Choose the menu Project:Set Project Type, and turn on "Separate Strs". Now "update" to compile all the modules.
For Think C 5 users, there are some additional steps, to create the POV.π project file from scratch. Start up Think C, create a new project called POV.π, and add all the .c source files to the project. Here's the current segmenting strategy:
=== Segment (povNEditor) ===
FileQueue.c
POV.c
POVMalloc.c
ScreenUtils.c
TextEditor.c
=== Segment (textures) ===
pigment.c
texture.c
txttest.c
=== Segment (tokenize) ===
express.c
matrices.c
tokenize.c
=== Segment (macwindows) ===
animate.c
imagewindow.c
popupmenu.c
printf2window.c
progressdialog.c
savecmppict.c
stdcompressionglue.o
templatemenu.c
=== Segment (files) ===
dump.c
gif.c
gifdecod.c
iff.c
raw.c
targa.c
=== Segment (parse) ===
parse.c
=== Segment (render) ===
normal.c
povray.c
ray.c
render.c
vect.c
=== Segment (polyquad) ===
poly.c
quadrics.c
=== Segment (heightfields) ===
hfield.c
=== Segment (cameraNlights) ===
camera.c
lighting.c
=== Segment (primparse) ===
boxes.c
colour.c
csg.c
image.c
objects.c
planes.c
point.c
=== Segment (primparse2) ===
blob.c
bound.c
cones.c
discs.c
=== Segment (primparse3) ===
spheres.c
triangle.c
=== Segment (bezier) ===
bezier.c
=== Segment (ansi) ===
ANSI-020.FPU.NoConsole
MacTraps
MacTraps2
Choose the Edit:Options:Think C: menu, and change the following: Language:turn on Check Pointer Types and Think C Language Extensions. Compiler settings, turn on all checkboxes except "4 byte ints" and "8 byte Doubles". Code Optimizations:turn on all. Debugging:turn off all. Prefix:add a #define _NOCONSOLE_. Choose the menu Project:Set Project Type, and turn on "Separate Strs", set the Creator to "PvRy", set the Size Flags to 58E0, set the type to Application, and set the Partition to 1000. Insert the following into the Prefix options from the Edit menu:
#define SystemSixOrLater true
#define _NOCONSOLE_ // turn off Think C console I/O
#include <MacHeaders>
#define NEEDS_68020 1 // turn on to force 68020 or better CPU code
#define NEEDS_COLORQD 1 // turn on to force Color Quickdraw ROM Support
#define NEEDS_32BITQD 1 // turn on to force 32Bit Quickdraw ROM Support
#define NEEDS_FPU 1 // turn on to force 68881 FPU calls
#define USE_NATIVE_MALLOC 1 // turn off to use C's malloc(), on for Mac's NewPtr()
After you build the application, you must set the application's (preferred) memory size to 2500, using the Finder's "Get Info" menu item. This is currently the only way to set the minimum and preferred memory sizes differently.
MPW C Compiler Notes
----------------------
The non-FPU version of POV-Ray was compiled under MPW, because the code generated was too big for Think C (specifically, hfield.c.) An MPW compile of the FPU version of POV-Ray is possible, but generates a noticeably larger and slower application.
POV-Ray has been compiled and tested using Apple's MPW C compiler, version 3.2.2 and 3.3. The make file supposedly supports MPW 3.0 and 3.1 as well, but has not been tested.
In order to compile POV-Ray with the included make file, you will first need to manually create an empty folder inside the POV-Ray Source folder called “obj”. The object files will be stored in there, instead of being sprinkled through the source code folder.
MPW 3.2 doesn't have the following QuickTime headers, so we have provided them for now. You will need to copy them into MPW's Interfaces:CIncludes folder.
ImageCodec.h
ImageCompression.h
MediaHandlers.h
Movies.h
MoviesFormat.h
QuickTimeComponents.h
You will also need to put the file "stdcompressionglue.o" into MPW's :Libraries:Libraries: folder.
There are quite a few flags used to turn on and off options (FPU, native-malloc, etc.), these are in the Make file itself.
There are some warnings that show up in the POV-Ray core code, all of them are due to unused function parameters. These are, in the immortal words of Douglas Adams, “Mostly Harmless.”
PowerPC Compiler Notes
----------------------
The PowerPC compile is being done by David Harr, and is as preliminary as the PowerPC development system for now. David Harr can be reached at wirehead@netcom.com.
